How to Modify Animal Crossing e-Reader Card Data 
by Hunter Rafferty 


This tutorial will detail, step-by-step, how to modify the data found specifically in Animal 
Crossing e-Reader cards. A lot of this information is applicable to other e-Reader cards, but this 
tutorial focuses solely on the cards that are meant to be scanned in the Post Office in the 
original Animal Crossing for the GameCube. 


This can be useful for writing custom e-Reader cards that send custom letters and items only 
obtainable through this method. Most importantly, this can be used to finally obtain the NES 
furniture items Super Mario Bros and Legend of Zelda that can only legitimately be obtained 
through this method. These cards will work on a vanilla console with no modifications. 


This tutorial is only for the North American e-Reader and that region’s associated card data. 
Japanese e-Reader data works similarly, but has differing flags that will not be covered. 


This process was documented in order to make it easier for any potential future devs / modding 
communities to have access to. The e-Reader in general is a rather niche peripheral and | don’t 
expect many people to get value out of this, but if this tutorial can help even a few people down 
the line then it will have served its purpose. 


WARNING: This tutorial is for relatively advanced users that have basic knowledge of Git, 
coding, hexadecimals, and bit logic. This tutorial also assumes you know basic command line 
prompts and how to run executable files from the command line. If you are simply curious about 
the process or are looking for downloads, you can find a better document here. 


If you’re still willing to follow the tutorial, please read every word of the guide carefully 
and make sure to follow the directions exactly. The e-Reader data format is over 20 years old 
and many of the tools in this tutorial are also rather ancient in internet standards. | tried to make 
it as painless as possible so if you’re going to try it for yourself, please follow the instructions 
carefully! 


Requirements 
You will need a PC running Windows 10 or higher 
You will need Python 3 


You will need CaitSith2’s e-Reader development tools 
You will need access to these e-Reader decoder/encoder assist tools 


You will need BlackShark’s e-Reader header correcting tool 
You will need a hex editor, like HxD 
You will need access to e-Reader card data in . raw format 


Tutorial 


1. Download the source code from the latest release of the e-Reader decoder/encoder 


assist tools and extract it. 


2. Enter the folder /eReader-Compression/. This will be your root folder. 


3. Download and extract CaitSith2's Dot Dode Dev Package to the root folder. 


4. Your root folder should now contain several new files, but you can delete all the new files 


except nedcenc.exe, nedclib.dl1l, and nevpk.exe. Alternatively, you can 
download these separately from CaitSith2's site and put them in the root folder. Your 


directory should look like this: 


eReader-Compression-1.0.0.zip » eReader-Compression-1.0.0 


Name 
MB cards 
El bin-to-raw.bat 
B bin-to-vpk.py 
Bl dec-to-vpk.bat 


Ei raw-to-bin.bat 


BB README.md 


B vpk-to-bin.py 


Bi vpk-to-dec.bat 


Type 

File folder 
Windows Batch File 
Python File 
Windows Batch File 
Windows Batch File 
MD File 

Python File 


Windows Batch File 


CG 


Compressed size 


5. Place only ONE . raw e-Reader card data in the /cards/raw/ folder. Doing multiple 


instances at a time may screw up the process. 


6. Run raw-to-bin.bat to automatically decode the . raw file in said folder into . bin. 
These new .bin files are placed in /cards/bin/. 


7. Runbin_ to vpk.py to automatically decode the .bin file into separate .header 
and .vpk chunks. These files are placed in /cards/vpk/ 


8. You should now have 2 .vpk files appended with -GBA and -Gc and one . header file. 
The -GBA file controls the letter that appears on the Game Boy Advance when scanned 
into the e-Reader bios. The -Gc file controls most of the GameCube data in Animal 
Crossing; the actual letter and present that are sent. 


9. Open the .header file in your hex editor and look at the final two bytes. These bytes 
represent the size of the -GBA .vpk in bytes. These two bytes are written in little 
endian, meaning if the final two bytes of the header read DB 05 then the actual value is 
0x05DB in hex. Refer to the diagram of a . header file below. 


Oa Ob Oc Od Oe OF 


00000000 10 12 |e0 41)|01)00 
00000010 | , [4e 49 4e 54 45 Te ° 
00000020 | . 00 00 

00000030 00 00 


00000040 00 00 ae ID (always 'NINTENDO') 
00000050 6f 73 -Ani 

00000060 00 00 : $e PK Size Info 

00000070 0 


In this header, the VPK size is 0x05DB which equals 1499 in decimal. This means that 
the first 1499 bytes of the -GBA .vpk are the relevant pieces of data for scanning into 
the e-Reader. Any remaining bytes in the . vpk are used for headering the -GC .vpk 
data. 


10. Make note of your VPK size info value in the .header and convert it to decimal 
following the example above. 


11. Open the -GBA_ .vpk file in your hex editor and navigate to the data that occurs after 
the relevant bytes dictated by the VPK size value. For example, if my VPK size value 
was 1499, | would navigate to the 1500th byte and start there. 


12. Select all the bytes from the end of your VPK size value to the end of the file. In the 
example below, that is all the values starting with 03 10 2E... 


00000000 00 01 O02 03 04 05 06 07 08 09 Oa Ob Oc Od Oe Of 


00000520 we Wel ae Wel 
00000530 pen 
00000540 ..C A7TEVOyCYi».€ 
00000550 .C.>'£8.6.§300<€ 
00000560 wN @?0..p..9..ya 
00000570 @?0..p.. Vx. Vp.u 


00000580 yuyoycylyYy< o#y 
00000590 -Ac¥a$a° .W1’ !4c 
000005a0 IT. ,.-A$0. .A#0.@N 
000005b0 : A£¥Ua. .T 


000005c0 
000005d0 els 
000005e0 


13. Cut this data out of this file and paste it into a new file. This data serves as a header for 
the -GC_ .vpk data, and the final two bytes of this data dictate the size of the -Gc 
.vpk, similarly to the global . header. We will need to re-append this later so do not 
lose it. 


14. Save these changes to your -GBA_ .vpk. 


15. Back in your root folder, run vpk-to-dec.bat to automatically decode the .vpk 
chunks into readable, decompressed files that you can modify with your hex editor. You 
should now have two files within your /cards/dec/ folder. If you wish to modify the 
data that appears on the GBA when swiping a card in the e-Reader bios, you can open 
the -GBA file in a hex editor and edit the data. However, for this tutorial, | will only be 
going over modifying the data that gets sent to Animal Crossing; that is, the -Gc file. 


16. Open the decompressed -Gc file in your hex editor and refer to the following image to 
edit the text and item data within. Modifying this data will edit the letter and attached gift 
that is sent to your house after you use the e-Reader card at the Post Office. 


000003ae | 00 01 O02 03 04 05 06 07 08 09 Oa Ob Oc Od Oe OF 


00000000 

00000010 I've bee 
00000020 n holding on to 
00000030 fthis for a whil 
00000040 e, but I fthin 
00000050 k you deserve it 
00000060 . Youtdefinitely 
00000070 won't find this 
00000080 fgame anywhere 
00000090 else - that'sif 
000000a0 or certain! 
000000b0 

000000c0 

000000d0 Keep sho 
000000e0 pping, Mr. Nook 
000000f0 7HD. . .8 
00000100 


In this example, you can clearly see the letter text on the right. You may edit this to say 
anything you want as long you remain within the letter character limit. The bytes with hex 
values CD represent a newline within the letter, which is useful for legibility. The bytes 
highlighted above, from offset 0F 9-OFA, control what item is attached to the letter. This 
value is represented as an item code assigned to every item in Animal Crossing. To 
reference which codes correspond to which items, see this data megasheet. In the 
example above, the item is set to 1DEC which is equivalent to the Super Mario Bros NES 
item. 


17. Edit the file to your liking, just ensure you don't include anything the game will not 
recognize, such as an invalid item code or invalid characters in the letter. Once 
complete, save the file. 


18. Back in the root folder, run dec-to-vpk.bat to compress the decompiled files back to 
. vpk. These compressed .vpk files will overwrite the ones in your /cards/vpk/ 
folder. If you do not wish for this to happen, rename your existing . vpk files before 
running the .bat. 


These next steps are extremely important, so pay close attention! 


19. Open your -GBA .vpk and your -GC .vpk in your hex editor. Make note of the size of 
both files in bytes. This has to be exactly correct later, so write it down! This is because 
re-compressing the files does not return them to their exact original size, resulting in 
some data flags being invalid in other places which we need to correct. 


20. In your -GBA .vpk, paste the bytes you cut previously in step 13 at the end of this file. 


0000085F |} O00 01 02 03 04 05 06 07 08 09 Oa Ob Oc Od Oe OF 


00000500 08  €Amé...A.+a@. "x. 
00000510 19 BOs corey Gece 
00000520 10 Bri am eae 
00000530 3Ff =—s_s«« .bC€aE. or. . YW? 
00000540 cO sp. WG HA.0.z3€XA 
00000550 e0 .f£=43E.M...9..ya 
00000560 fd @?0..p..y..ya@?y 
00000570 £9 yyovityvy?p. ayu 
00000580 01 YyoA.8§“°LzA20<!. 
00000590 08  évE".D<bo )uaM . 
000005a0 c4 i 
000005b0 er) 

000005c0 

000005d0 

000005e0 


In this example above, we appended the data we cut previously. The highlighted final 
two bytes of this data represent the size of the -GC_ .vpk in hexadecimal. This is again 
written in little endian and must represent the size of the -GC_ .vpk. In my case, the 
-GC .vpk was 187 bytes long or 0x00BB in hexadecimal, so | rewrote the final bytes to 
represent 0xOOBB. 


21. Following the example above, replace the final two bytes in -GBA .vpk to represent the 
size of your -GC_ .vpk in hexadecimal and save the file. 


22. Next open your original . header file, which should also be located in /cards/vpk/. 
We will need to edit a few things here which can get complex, so pay close attention. 


00000000 
00000010 | | 
00000020 | | 


00000030 
00000040 
00000050 
00000060 
00000070 


23. 


24. 


25. 


Oa Ob Oc Od Oe Of 
10 12 |e0 41)|01)00 


[4e 40 fe 54 45 fe’ 

00 00 00 00 50 7c 

00 00 0000 0000... 

00 00 00 00 00 00 : noe ID Calways 'NINTENDO') 
6f 73 73 69 6e 67 

00 00 00 00 00 00 


Revisiting the header, the information we’re interested in modifying is the VPK size info 
flag in teal and the general size info flag in green. 


Modifying the VPK size info flag is as simple as replacing the final two bytes with the size 
of your -GBA .vpk in hexadecimal. This is the same process as step 20, but for the 
-GBA .vpk this time. Convert your byte size into hexadecimal and edit the bytes to 
represent this new size in little endian. 


Modifying the general size flag in green is a lot more complex and requires some bit 
logic and explanation. Firstly, the size info flag is actually a 32-bit value read from right to 
left. In the above example, the hex value representing this value is 0xO0O20BBA22. You 
will need to convert this value to binary for the next steps, so convert it now. 


In the example above, 0x020BBA22 converted to binary is: 


0000 0010 0000 1011 1011 1010 0010 0010 


Here, bits 9-24 (in red) represent the original VPK size info flag value + 2 exactly. For 
example, the VPK size info flag in the above example is 0x05DB. Doing some math, 
0x05DB + 2 = 0x05DD, which when converted to binary yields 0000 0101 1101 
1101. You can see this value aligns perfectly with bits 9-24 in the general size flag: 


0000 0010 0000 1011 1011 1010 0010 0010 
0 0000 1011 1011 101 


You now need to add 2 to your new VPK size you wrote in step 23 and convert this value 
into binary. For example, if my VPK size is 0x05A8 | would add 2 to get 0x05AA and 
convert this value to binary to get 0000 0101 1010 1010. 


26. Take this binary value and replace bits 9-24 in the general size flag with this new value. 


Example: 


0000 0010 0000 1011 1011 1010 0010 0010 
0 0000 1011 0101 010 


0000 0010 0000 1011 0101 0100 0010 0010 


27. Finally, convert this 32-bit binary 
general size flag within the .hea 
to hexadecimal would be 0x020! 


back to hexadecimal and write the value back into the 
der file. For example, the above binary converted back 
B5422, so my .header would look like this: 


0000031d | 00 01 O02 03 04 05 06 07 08 09 Oa Ob Oc Od Oe Of 


00000000 
00000010 
00000020 
00000030 


00000040 
00000050 
00000060 
00000070 
00000080 


28. Save your changes to the . header file and close your hex editor. No files must be 
opened by any programs at this point. 


29. Back in the root folder, run vpk-to-bin.py to compress back to . bin. This will once 
again overwrite the .bin file in /cards/bin/. 


30. Open this new .bin file in your hex editor. If your file is not exactly 2112 bytes, you will 
need to add padding in the form of 00 or FF at the end of the file until it is exactly that 
size. It should go up to offset 0840. Save the file once done. 


0000094F | 00 01 02 03 04 05 06 07 08 09 Oa Ob Oc Od Oe OF 


000006cO | 09 52 45 3b 42 01 
000006d0 | c7 17 47 43 Oc cl 
000006e0 | 7b c4 70 38 6f le 
000006F0 | 09 23 70 eb bi ad 
00000700 | 00 00 00 00 00 00 
00000710 | 00 00 00 00 00 00 
00000720 | 00 00 00 00 00 00 
00000730 | 00 00 00 00 00 00 
00000740 | 00 00 00 00 00 00 
00000750 | 00 00 00 00 00 00 
00000760 00 00 00 00 00 00 
00000770 00 00 00 00 00 00 
00000780 | 00 00 00 00 00 00 
00000790 | 00 00 00 00 00 00 
000007a0 | 00 00 00 00 00 00 
000007b0 | 00 00 00 00 00 00 
000007c0 | 00 00 00 00 00 00 
000007d0 | 00 00 00 00 00 00 
000007e0 | 00 00 00 00 00 00 
000007f0 | 00 00 0000 00 00 
00000800 | 00 00 00 00 00 00 
00000810 | 00 00 00 00 00 00 
00000820 

00000830 


6c 71 98 4e d3 10 -RE;B.1 
08 44 10 1d 
91 43) 4e 58 
08 00 00 47 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 
00 00 00 00 


a1. 


32. 


33. 


34. 


Extract BlackShark’s header correction tool to any folder you wish, and open the root 
folder so you can see headerfix.exe. 


Drag your .bin file from /cards/bin/ directly over headerfix.exe to automatically 
fix any checksum flags present in the header. The card will not read properly without 
running it through this tool. This will overwrite your .bin automatically. 


If everything went smooth, run bin-to-raw.bat to convert back to . raw and you’re 
done! This . raw file can now be used with Dolphin Emulator or be printed into a 
physical dot code to scan on a real console! 


If you wish to turn this . raw file into a printable dot code to scan on a physical e-Reader, 
see this video tutorial by Anzomia. 


Troubleshooting 


| would highly recommend testing on Dolphin Emulator before attempting to print the dot code 
physically. 


e lf you run into a READ ERROR on your emulated e-Reader, you likely made a mistake 
when setting the VPK or general size flag checks in the header data. Check that these 
are correct. 


e If you run into a “this is not a character card” error, you likely made a mistake when 
re-appending the VPK data in step 20. Make sure your size bytes are correct! 


e If your card scans on the e-Reader BIOS but not in the Animal Crossing application, you 
have made a mistake editing the -Gc data or your information in the re-appended VPK 
data in step 20 is incorrect. 


e If the headerfix.exe program gives you a size error, your . bin file is not 2112 bytes 
in length. Be sure to append filler data to make the file the appropriate size. 


e lf the card reads successfully but crashes the Game Boy Advance, then your checksums 
are incorrect. Make sure you run your .bin file through headerfix.exe! 


e If your card works on emulator, but you’re getting a READ ERROR on your physical dot 
code/e-Reader, then there is a problem with your printed dot code. You may need to 
mess around with your printer settings to get a perfect print. 600x600dpi or higher 
printed on quality glossy photo paper is recommended. 


e lf the card does not read at all then it’s impossible to know what went wrong — you will 
need to redo the entire process. 


e If none of the above is helpful, see the contact section below. 


Contact 


If you’re interested in this work or have further troubleshooting questions, you can contact me 
personally: 


Discord: thehuntinghunter 
Email: hunter.rafferty@outlook.com 


